home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 June: Reference Library / Dev.CD Jun 96 RL / Dev.CD Jun 96 RL.toast / What's New? / Development Kits / Apple Game Sprockets DR1 / Headers / DrawSprocket.h next >
Encoding:
C/C++ Source or Header  |  1996-04-24  |  8.1 KB  |  301 lines  |  [TEXT/CWIE]
  1. /*
  2. ********************************************************************************
  3. **
  4. **    File:        DrawSprocket.h
  5. **
  6. **    Author(s):    Dan Venolia (DV)
  7. **                Cary Farrier (CF)
  8. **
  9. **    Contents:    DrawSprocket interface file.
  10. **
  11. **    Copyright (c) 1995-96 Apple Computer, Inc.
  12. **                
  13. ********************************************************************************
  14. */
  15.  
  16. #ifndef __DrawSprocket_h__
  17. #define __DrawSprocket_h__
  18.  
  19. #include <Types.h>
  20. #include <Events.h>
  21. #include <Quickdraw.h>
  22. #include <QDOffscreen.h>
  23.  
  24. #ifdef __cplusplus
  25. extern "C" {
  26. #endif
  27.  
  28. /*
  29. ********************************************************************************
  30. ** error codes
  31. ********************************************************************************
  32. */
  33. enum {
  34.     kDSInvalidDisplayObjectErr        = -4600L,
  35.     kDSGDeviceBusyErr,
  36.     kDSGDeviceNotFoundErr,
  37.     kDSInvalidParameterErr,
  38.     kDSNotEnoughMemoryErr,
  39.     kDSGammaTableDataTooWideErr,
  40.     kDSDisplayManagerTooOldErr,
  41.     kDSInvalidBackBufferErr,
  42.     kDSNotEnoughPagesErr,
  43.     kDSFeatureNotInHWErr
  44. };
  45.  
  46. /*
  47. ********************************************************************************
  48. ** constants
  49. ********************************************************************************
  50. */
  51.  
  52. enum {
  53.     kSmoothFadeOut    = -1L,
  54.     kSmoothFadeIn     = -2L
  55. };
  56.  
  57. enum {
  58.     kDisplayDepthMask1        = 1U<<0,
  59.     kDisplayDepthMask2        = 1U<<1,
  60.     kDisplayDepthMask4        = 1U<<2,
  61.     kDisplayDepthMask8        = 1U<<3,
  62.     kDisplayDepthMask16        = 1U<<4,
  63.     kDisplayDepthMask32        = 1U<<5,
  64.     kDisplayDepthMaskAll    = ~0U
  65. };
  66.  
  67. /*
  68. ** use this in colorNeeds to specify if you must have color
  69. ** (kDisplayColorRequire), you prefer color (kDisplayColorRequest) but
  70. ** can live without it (you may get B&W or grayscales), or you just don't
  71. ** care (kDisplayColorDontCare) and can work with any type of display
  72. ** because you are a god.
  73. */
  74. enum {
  75.     kDisplayColorDontCare    = 0L,
  76.     kDisplayColorRequest    = 1L,
  77.     kDisplayColorRequire    = 2L
  78. };
  79.  
  80. enum {
  81.     kDisplayPlayStateActive        = 0L,
  82.     kDisplayPlayStatePaused        = 1L,
  83.     kDisplayPlayStateInactive    = 2L
  84. };
  85.  
  86. enum {
  87.     kDisplaySpecialQD3DAccel        = 1U<<0,
  88.     kDisplaySpecialDoubleBuffer        = 1U<<1,
  89.     kDisplaySpecialPageFlip         = 1U<<2
  90. };
  91.  
  92. /*
  93. ** kDisplaySpecialBuffered is a handy way to specify that you want
  94. ** some form of double buffering in specialFlags, but don't put it in the
  95. ** specialFlagsInHW field or it will almost never match
  96. ** (kDisplaySpecialDoubleBuffer in HW is rare).
  97. */
  98. #define kDisplaySpecialBuffered \
  99.     ( kDisplaySpecialDoubleBuffer | kDisplaySpecialPageFlip )
  100.  
  101. /*
  102. ********************************************************************************
  103. ** data types
  104. ********************************************************************************
  105. */
  106. typedef void *DisplayObject;
  107.  
  108. /* a DSBusyProcPtr must return true if the display object is busy */
  109. typedef Boolean (*DSBusyProcPtr)(DisplayObject inDisplayObject,
  110.     UInt32 inUserRefCon );
  111.  
  112. /*
  113. ** a DSUserEventProcPtr is used to process events when the user display
  114. ** selection dialog is active
  115. */
  116. typedef pascal Boolean (*DSUserEventProcPtr)( EventRecord *inEvent );
  117.  
  118. struct DisplayConfig {
  119.     /*
  120.     ** these describe the device & mode being used
  121.     */
  122.     GDHandle            device;
  123.     UInt32                mode;
  124.     UInt32                frequency;
  125.  
  126.     /*
  127.     ** these are the dimensions that you would like to render into
  128.     */
  129.     UInt32                width;
  130.     UInt32                height;
  131.     
  132.     /*
  133.     ** set colorNeeds to tell DS if you need color, or if
  134.     ** a b/w or grayscale display is OK
  135.     */
  136.     UInt32                colorNeeds;
  137.     
  138.     /*
  139.     ** this is the initial color table you want to start with,
  140.     ** only useful for indexed modes
  141.     */
  142.     CTabHandle            colorTable;
  143.  
  144.     /* 
  145.     ** specialFlags indicates your requirements in general (emulation
  146.     ** of the capablity by DS is OK), and specialFlagsInHW indicates
  147.     ** the DS capabilites which you require NOT to be emulated
  148.     */
  149.     UInt32                specialFlags;
  150.     UInt32                specialFlagsInHW;
  151.  
  152.     /*
  153.     ** these are the depths that are acceptable to the game, set
  154.     ** as many as are acceptable
  155.     */
  156.     UInt32                backBufferDepthMask;
  157.     UInt32                frontBufferDepthMask;
  158.     
  159.     /*
  160.     ** best depth will tell DS what possible depth in the
  161.     ** depth mask is the best one to use when it has a choice
  162.     */
  163.     UInt8                backBufferBestDepth;
  164.     UInt8                frontBufferBestDepth;
  165.  
  166.     /*
  167.     ** when pageCount is an output, it indicates the number of
  168.     ** video pages available.  A value of 1 means that the pages
  169.     ** would be implemented in software, and will be limited by
  170.     ** the amount of memory in the system.
  171.     **
  172.     ** when pageCount is an input, it indicates the number of
  173.     ** video pages to be used by the game.  Currently DS will ignore
  174.     ** pageCount in this context and only allow double buffering, but
  175.     ** this will be used when we add support for N buffering.  For now
  176.     ** it will return kDSNotEnoughPagesErr if this value is anything
  177.     ** other than 2 on input.
  178.     */
  179.     UInt8                pageCount;
  180.     
  181.     /*
  182.     ** if you set these to anything other than 0 you will look very very silly
  183.     ** in future versions of DS, people will laugh at you, and you will have
  184.     ** to move into a cardboard box
  185.     */
  186.     UInt8                reserved1;
  187.     UInt32                reserved2;    
  188.     
  189. };
  190. typedef struct DisplayConfig DisplayConfig;
  191.  
  192. /*
  193. ********************************************************************************
  194. ** debug prototypes, operational only in the debugging version of DS
  195. ********************************************************************************
  196. */
  197.  
  198. /*
  199. ** set this to TRUE to bypass gamma fading & the blanking window, they
  200. ** can make it hard to debug :-)
  201. */
  202. void DSpSetDebugMode( Boolean inDebugFlag );
  203.  
  204. /*
  205. ********************************************************************************
  206. ** prototypes
  207. ********************************************************************************
  208. */
  209. OSStatus DisposeDisplay( DisplayObject inDisplayObject );
  210.  
  211. OSStatus FadeDisplayGamma( DisplayObject inDisplayObject,
  212.             SInt32 inPercentOfOriginalIntensity, /* 50 = 50%, 150 = 150%, etc */
  213.             RGBColor *inZeroIntensityColor );
  214.  
  215. OSStatus FindGDeviceFromConfig( DisplayConfig *ioConfig );
  216.  
  217. OSStatus GetDisplayActualConfig( const DisplayObject inDisplayObject,
  218.             DisplayConfig *outActualConfig );
  219.  
  220. OSStatus GetDisplayBackBuffer( const DisplayObject inDisplayObject,
  221.             GWorldPtr *outGWorld );
  222.  
  223. OSStatus GetDisplayConfig( const DisplayObject inDisplayObject,
  224.             DisplayConfig *outConfig );
  225.  
  226. UInt32   GetDisplayFrameCount( const DisplayObject inDisplayObject );
  227.  
  228. UInt32   GetDisplayFrameSkip( const DisplayObject inDisplayObject );
  229.  
  230. OSStatus GetDisplayFrontBuffer( const DisplayObject inDisplayObject,
  231.             GWorldPtr *outGWorld );
  232.  
  233. GDHandle GetDisplayGDevice( const DisplayObject inDisplayObject );
  234.  
  235. OSStatus GetDisplayPlayState( const DisplayObject inDisplayObject,
  236.             UInt32 *outPlayState );
  237.  
  238. OSStatus GetModeCapabilities( DisplayConfig *ioConfig );
  239.  
  240. OSStatus GetModeCount( const GDHandle inGDevice, UInt32 *outModeCount );
  241.  
  242. Boolean  IsDisplayBusy( const DisplayObject inDisplayObject );
  243.  
  244. OSStatus NewDisplay( const DisplayConfig *inConfig,
  245.             DisplayObject *outDisplayObject );
  246.  
  247. OSStatus RestoreSavedGDevice( const GDHandle inGDevice, GDHandle *outGDevice );
  248.  
  249. void     SetBlankingColor( const RGBColor *inRGBColor );
  250.  
  251. void     SetDisplayFrameSkip( DisplayObject inDisplayObject,
  252.             UInt32 inFrameSkip );
  253.  
  254. OSStatus SetDisplayPlayState( DisplayObject inDisplayObject,
  255.             UInt32 inPlayState );
  256.  
  257. OSStatus SwapDisplayBuffers( DisplayObject inDisplayObject,
  258.             DSBusyProcPtr inUserBusyProc, UInt32 inUserRefCon );
  259.     
  260. #if 0
  261. /*
  262. ********************************************************************************
  263. ** calls beyond this point are not implemented yet
  264. ********************************************************************************
  265. */
  266.  
  267. OSStatus UserSelectGDevice(
  268.     DisplayConfig *ioConfig,
  269.     DSUserEventProcPtr inUserEventProc,
  270.     Str255 inUserPrompt );
  271.     
  272. OSStatus InvalDisplayRect(
  273.     const DisplayObject inDisplayObject,
  274.     const Rect *inRect ); /* rect describes a pixel area, not a logical area */
  275.     
  276. OSStatus SetMaxInvalidRects(
  277.     const DisplayObject inDisplayObject,
  278.     UInt32 inMaxInvalidRects );
  279.         
  280. OSStatus SetDisplayCLUTEntries(
  281.     const DisplayObject inDisplayObject,
  282.     const ColorSpec *inEntries,
  283.     UInt16 inStartingEntry,
  284.     UInt16 inEntryCount );
  285.     
  286. OSStatus GetDisplayCLUTEntries(
  287.     const DisplayObject inDisplayObject,
  288.     ColorSpec *outEntries,
  289.     UInt16 inStartingEntry,
  290.     UInt16 inEntryCount );
  291.     
  292. OSStatus SuspendResumeDrawSprocket(
  293.     Boolean inSuspendingFlag );
  294. #endif /* 0 */
  295.  
  296. #ifdef __cplusplus
  297. }
  298. #endif
  299.  
  300. #endif /* __DrawSprocket_h__ */
  301.